Add protocol level receiver frame rate measurement for SUMD
[betaflight.git] / docs / Inflight Adjustments.md
blob3c9ae89c3ec54699e2b15fcbc06730ecdcd00427
1 # In-flight Adjustments
3 With Cleanflight it's possible to make adjustments to various settings by using AUX channels from your transmitter while the aircraft is flying.
5 ## Warning
7 Changing settings during flight can make your aircraft unstable and crash if you are not careful.
9 ## Recommendations
11 * Always make adjustments while flying in a large open area.
12 * Make small adjustments and fly carefully to test your adjustment.
13 * Give yourself enough flying space and time to adjust to how your changes affect the behaviour of the aircraft.
14 * Remember to set adjustment channel switches/pots to the center position before powering on your TX and your aircraft.
15 * If possible configure switch warnings on your transitter for dedicated adjustment switches. 
16 * A momentary 3 position switch is the best choice of switch for this - i.e. one that re-centers itself when you let go of it.
18 ## Overview
20 There are two modes of operation. The first supports adjusting settings by incrementing/decrementing them through use of an aux channel, typically a three position switch, where the middle position makes no change, and the other positions either increment or decrement the selected setting.
22 The other mode is Absolute mode where a pot (knob/slider) may be directly mapped and changes the selected setting to a value based on a center value, coresponding to mid-postion on the pot and a range of ± adjustment at the min/max positions of the pot.
24 Both modes utilise two channels to make an adjustment.
26 | Channel | Use |
27 | ------- | --- |
28 | Range | This channel is used to enable an adjustment. When the channel is set to fall withing the specified range, then the corresponding adjustment is enabled. This is similar to mode setting where a given mode is enabled when a channel is within a lower and upper range. |
29 | Adjustment | This channel is used to control the change to the specified setting|
31 Settings are not saved automatically, connect a GUI, refresh and save or save using stick position when disarmed.
32 Powering off without saving will discard the adjustments.
34 Settings can be saved when disarmed using stick positions: Throttle Low, Yaw Left, Pitch Low, Roll Right.
36 ### Increment/Decrement mode
38 Up to 4 RX channels can be used to make different adjustments at the same time.
40 The adjustment the Adjustment Channel makes is controlled by the Range Channel.
42 The available adjustments are listed in [this table](#adjustment-functions).
44 Example scenarios:
45 Up to 4 3-position switches or pots can be used to adjust 4 different settings at the same time.
46 A single 2/3/4/5/6/x position switch can be used to make one 3 position switch adjust one setting at a time.
48 Any combination of switches and pots can be used. So you could have 6 POS switch.
50 #### Adjustment switches
52 The Adjustment switch is associated with the Adjustment Channel. The switch can be a ON-OFF-ON, POT or momentary ON-OFF-ON switch.  The latter is recommended.
54 When the switch is returned to the center position the value will not be increased/decreased.
56 Each time you can press the switch high/low and then return it to the middle the value will change at least once, you do not have to wait before pressing the switch again if you want to increase/decrease at a faster rate.  While the adjustment switch held is high/low, the adjustment function applies and increases/decreases the value being adjusted twice a second and the flight controller will beep shorter/longer, respectively. The system works similar to how a keyboard repeat delay works.
58 Hint: With OpenTX transmitters you can combine two momentary OFF-ON switches to control a single channel.  You could make it so that a momentary switch on the left of your transmitter decreases the value and a momentary switch on the right increases the value.  Experiment with your mixer!
60 ### Absolute mode
62 The adjustment is made where the Adjustment Channel is an Aux channel connected to a pot (knob/slider). This provides an easier approach than using the Increment/Decrement mode as it is easier to keep track of the setting.
64 Note that if the same pot is used as the Adjustment Channel to make multiple adjustments, there is a risk of a jump in values of the second setting when switching from the first if the pot is not centered. To avoid this it is recommended that if adjusting two different settings using the same pot, a three position switch be used for the Range Channel, with neither setting associated with the middle position.
66 ## Configuration
68 The CLI command `adjrange` is used to configure adjustment ranges.
70 12 adjustment ranges can be defined.
72 Show the current ranges using:
74 `adjrange` 
76 Configure a range using:
78 `adjrange <index> 0 <range channel> <range start> <range end> <adjustment function> <adjustment channel>`
82 | Argument | Value | Meaning |
83 | -------- | ----- |-------- |
84 | Index | 0 - 29 | Select the adjustment range to configure |
85 | 0 | 0 | Used as slot before Betaflight 4.1 |
86 | Range Channel | 0 based index, AUX1 = 0, AUX2 = 1 | The AUX channel to use to select an adjustment for a switch/pot | 
87 | Range Start | 900 - 2100. Steps of 25, e.g. 900, 925, 950... | Start of range | 
88 | Range End | 900 - 2100 | End of range |
89 | Adjustment function | | See [Adjustment functions table](#adjustment-functions) |
90 | Adjustment channel | 0 based index, AUX1 = 0, AUX2 = 1 | The channel that is controlled by a 3 Position switch/Pot |
91 | Center Value | If this is non-zero then Absolute Mode is used for this range otherwise Increment/Decrement Mode is used. In Absolute Mode this value is the value which will be assigned to the setting when the Adjustment Channel is set to mid-position. |
92 | Scale Value | This specifies the amount that will be subtracted/added to the center value when the Adjustment Channel is at min/max respectively. |
94 Range Start/End values should match the values sent by your receiver.
96 The Range Channel and the Adjustment Channel can be the same channel.  This is useful when you want a single 3 Position switch to be dedicated
97 to a single adjustment function regardless of other switch positions.
99 The adjustment function is applied to the adjustment channel when range channel is between the range values.
100 The adjustment is made when the adjustment channel is in the high or low position.  high = mid\_rc + 200, low = mid\_rc - 200.  by default this is 1700 and 1300 respectively.
102 ### Adjustment functions
104 | Value | Adjustment | Notes |
105 | ----- | ---------- |------ |
106 | 0     | None | |
107 | 1     | RC RATE | Step / absolute setting |
108 | 2     | RC\_EXPO | Step / absolute setting |
109 | 3     | THROTTLE\_EXPO | Step / absolute setting |
110 | 4     | PITCH\_ROLL\_RATE | Step / absolute setting |
111 | 5     | YAW\_RATE | Step / absolute setting |
112 | 6     | PITCH\_ROLL\_P | Step / absolute setting |
113 | 7     | PITCH\_ROLL\_I | Step / absolute setting |
114 | 8     | PITCH\_ROLL\_D | Step / absolute setting |
115 | 9     | YAW\_P | Step / absolute setting |
116 | 10    | YAW\_I | Step / absolute setting |
117 | 11    | YAW\_D | Step / absolute setting |
118 | 12    | RATE\_PROFILE | Switch between 3 or 6 rate profiles (uses `rate_6pos_switch` setting) |
119 | 13    | PITCH\_RATE | Step / absolute setting |
120 | 14    | ROLL\_RATE | Step / absolute setting |
121 | 15    | PITCH\_P | Step / absolute setting |
122 | 16    | PITCH\_I | Step / absolute setting |
123 | 17    | PITCH\_D | Step / absolute setting |
124 | 18    | ROLL\_P | Step / absolute setting |
125 | 19    | ROLL\_I | Step / absolute setting |
126 | 20    | ROLL\_D | Step / absolute setting |
127 | 21    | RC\_RATE\_YAW | Step / absolute setting |
128 | 22    | PITCH\_ROLL\_F | Step / absolute setting |
129 | 23    | FEEDFORWARD\_TRANSITION | Step / absolute setting |
130 | 24    | HORIZON\_STRENGTH | Select the horizon strength |
131 | 25    | PID\_AUDIO | Select the PID value to be turned into tones |
132 | 26    | PITCH\_F | Step / absolute setting |
133 | 27    | ROLL\_F | Step / absolute setting |
134 | 28    | YAW\_F | Step / absolute setting |
135 | 29    | OSD\_PROFILE | Switch between 3 OSD profiles |
136 | 30    | LED\_PROFILE | Switch between the RACE / BEACON / STATUS LED strip profiles |
138 ## Examples
140 ### Example 1 - 3 Position switch used to adjust pitch/roll rate
143 adjrange 0 0 3 900 2100 4 3 0 0
146 explained:
148 * configure adjrange 0 so that when aux4
149 (3) in the range 900-2100 then use adjustment 4 (pitch/roll rate) when aux 4 (3)
150 is in the appropriate position. 
151 * note that Center/Scale values are both zero, so this range will use increment/decrement mode.
154 ### Example 2 - 2 Position switch used to enable adjustment of RC rate via a 3 position switch
157 adjrange 1 0 0 900 1700 0 2 0 0
158 adjrange 2 0 0 1700 2100 1 2 0 0
160 explained:
162 * configure adjrange 1 so that when aux1
163 (0) in the range 900-1700 then do nothing (0) when aux 3 (2) is in any
164 position.
165 * configure adjrange 2 so that when aux1
166 (0) in the range 1700-2100 then use adjustment rc rate (1) when aux 3
167 (2) is in the appropriate position.
168 * note that Center/Scale values are both zero, so this range will use increment/decrement mode.
170 Without the entire range of aux1 being defined there is nothing that
171 would stop aux 3 adjusting the pitch/roll rate once aux 1 wasn't in the higher
172 range.
174 ### Example 3 - 6 Position switch used to select PID tuning adjustments via a 3 position switch
177 adjrange 3 0 1 900 1150 6 3 0 0
178 adjrange 4 0 1 1150 1300 7 3 0 0
179 adjrange 5 0 1 1300 1500 8 3 0 0
180 adjrange 6 0 1 1500 1700 9 3 0 0
181 adjrange 7 0 1 1700 1850 10 3 0 0
182 adjrange 8 0 1 1850 2100 11 3 0 0
185 explained:
187 * configure adjrange 3 so that when aux2
188 (1) in the range 900-1150 then use adjustment Pitch/Roll P (6) when aux 4
189 (3) is in the appropriate position.
190 * configure adjrange 4 so that when aux2
191 (1) in the range 1150-1300 then use adjustment Pitch/Roll I (7) when aux 4
192 (3) is in the appropriate position.
193 * configure adjrange 5 so that when aux2
194 (1) in the range 1300-1500 then use adjustment Pitch/Roll D (8) when aux 4
195 (3) is in the appropriate position.
196 * configure adjrange 6 so that when aux2
197 (1) in the range 1500-1700 then use adjustment Yaw P (9) when aux 4
198 (3) is in the appropriate position.
199 * configure adjrange 7 so that when aux2
200 (1) in the range 1700-1850 then use adjustment Yaw I (10) when aux 4
201 (3) is in the appropriate position.
202 * configure adjrange 8 so that when aux2
203 (1) in the range 1850-2100 then use adjustment Yaw D (11) when aux 4
204 (3) is in the appropriate position.
205 * note that Center/Scale values are both zero, so this range will use increment/decrement mode.
207 ### Example 4 - Use a single 3 position switch to change between 3 different rate profiles
210 adjrange 11 0 3 900 2100 12 3 0 0
213 explained:
215 * configure adjrange 11 so that when aux4
216 (3) in the range 900-2100 then use adjustment Rate Profile (12) when aux 4
217 (3) is in the appropriate position.
218 * note that Center/Scale values are both zero, so this range will use increment/decrement mode.
220 When the switch is low, rate profile 0 is selcted.
221 When the switch is medium, rate profile 1 is selcted.
222 When the switch is high, rate profile 2 is selcted.
224 ### Example 5 - Use a single switch to enable absolute setting of Roll/Pitch P terms from two pots
227 adjrange 0 0 4 1450 1550 18 0 40 10
228 adjrange 1 0 4 1450 1550 15 1 58 20
231 explained:
233 * note that Center value is non-zero, so this range will use absolute mode.
234 * configure adjrange 0 so that when aux5 (3) in the range 1450-1550 then use aux 1 (0) to adjust Roll P Adjustment (18) such that the value will be 40 with the pot centered and 30/50 at min/max.
235 * configure adjrange 1 so that when aux5 (3) in the range 1450-1550 then use aux 2 (0) to adjust Pitch P Adjustment (15) such that the value will be 58 with the pot centered and 38/78 at min/max.
237 ### Example 6 - Use a single switch to enable absolute setting of Roll/Pitch P/I/D terms from three pots, selected using a single switch
240 adjrange 0 0 4 950 1050 18 0 40 20
241 adjrange 1 0 4 950 1050 19 1 107 53
242 adjrange 2 0 4 950 1050 20 2 76 38
243 adjrange 3 0 4 1950 2050 15 0 63 16
244 adjrange 4 0 4 1950 2050 16 1 138 69
245 adjrange 5 0 4 1950 2050 17 2 66 33
247 explained:
249 * note that Center value is non-zero, so this range will use absolute mode.
251 This assigns pots aux 1, aux 2, and aux 3 respectively to control P, I and D settings with the pots at mid-position giving the default P/I/D values and providing a range of adjustment of +/- 50%. When the aux 5 switch is in one end position then roll P/I/D will be adjusted and when the aux 5 switch is in the other end position, pitch P/I/D will be adjusted. In the aux 5 switch middle position nether will be adjusted. Thus one could center the pots, select roll on aux 5 and then adjust the P/I/D values in flight. Then land, move the aux 5 switch to center, center the pots, select pitch on the switch and then again adjust P/I/D in flight. 
253 ### Configurator examples
255 Note that the configurator does not currently support the Center/Scale values, however it may still be used to setup the ranges and then the CLI may be used to set the Center/Scale values.
257 The following 5 images show valid configurations.  In all cales the enture usable range for the Range Channel is used.
259 ![Configurator example 1](Screenshots/adjustments-rate-profile-selection-via-3pos.png)
263 ![Configurator example 2](Screenshots/adjustments-pitch-and-roll-rate-adjustment-via-3pos.png)
267 ![Configurator example 3](Screenshots/adjustments-pid-via-two-3pos.png)
271 ![Configurator example 4](Screenshots/adjustments-pid-via-6pos-and-3pos.png)
275 ![Configurator example 5](Screenshots/adjustments-rates-via-a-2pos-and-3pos.png)
277 The following examples shows __incorrect__ configurations - the entire usable range for the Range Channel is not used in both cases.
279 ![Configurator example 6](Screenshots/adjustments-incorrect-config-1.png)
280 ![Configurator example 7](Screenshots/adjustments-incorrect-config-2.png)
282 In the following example, the incorrect configuraton (above) has been corrected by adding a range that makes 'No changes'.
284 ![Configurator example 7](Screenshots/adjustments-incorrect-config-2-corrected.png)